XM Directory (XM Subscribers)¶

The methods in the XMDirectory module give you the ability to create contacts, delete contacts, list contacts, get a contact’s information, get the additional information about a contact all from the XMDirectory.

Create a Contact in the XMDirectory¶

XMDirectory.create_contact_in_XM(first_name=None, last_name=None, email=None, phone=None, language='en', metadata={})¶

This function gives you the ability to create a contact in your XM Directory. This method does not every item in that you just created, but it does return the XMDirectory contact id associated with the newly created contact.

Parameters

first_name (str) – The contacts first name.
last_name (str) – The contacts last name.
email (str) – the contacts email.
phone (str) – the contacts phone number.
language (str) – the native language of the contact. (Default: English)
metadata (dict) – any relevant contact metadata.

Returns

The newly created contact id (CID) in XMDirectory.

Example Implementation¶

Here is an example on how to implement the create_contact_in_XM() method. We will create a contact named John Smith in our XMDirectory.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import XMDirectory

#Create an instance
x = XMDirectory()

#Call the method
x.create_contact_in_XM(first_name='John', last_name='Snow', email='therealking@email.com', phone=None, language="en", metadata={})

This will return John Smith’s Contact ID in your XMDirectory.

'CID_FakeContactID'

Delete a Contact in the XMDirectory¶

Warning

Once you delete a contact from the XMDirectory, you will also delete them from any mailing list that the contact is associated with. Be sure that you want to implement this!

XMDirectory.delete_contact(contact_id=None)¶

This method will delete a contact from your XMDirectory. (Caution this cannot be reversed once deleted!)

Parameters: contact_id (str) – The unique id associated with each contact in the XM Directory.
Returns: Nothing, but prints if successful, and if there was an error.

Example Implementation¶

Here is an example on how to implement the delete_contact() method. Let’s say that we no longer want John Smith in our XMDirectory, here is how we would go about removing him.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import XMDirectory

#Create an instance
x = XMDirectory()

#Call the method
x.delete_contact(contact_id='CID_FakeContactID')

This will return that John Smith’s Contact ID has been deleted from your XMDirectory.

'Your XM Contact "CID_FakeContactID" has been deleted from the XM Directory.'

List the Contacts in the XMDirectory¶

XMDirectory.list_contacts_in_directory(page_size=1000, offset=0, url=None)¶

This method will list the top-level information about the contacts in your XM Directory. Depending on the argument that you pass to the parameter ‘to_df’, the method will either return a Pandas DataFrame or a dictionary containing the contact data. Use the parameters ‘page_size’ and ‘offset’ to dictate the size and position of the slice that you are requesting from the XMDirectory. As an additional point, when itteratively calling this function you may experience some latency, so as a courtesy to Qualtrics and their Dev team I recommend calling time.sleep(3) between each request.

Parameters

page_size (int) – This parameter sets chunk size of the number of contacts requested.
offset (int) – This parameter specifies the where start index value of the call. (i.e offset = 300 means start the request at the 300th contact in the directory.)
to_df (Boolean) – If True, the contacts will be returned in a Pandas DataFrame. If False, a Dictionary is returned.

Returns

A Pandas DataFrame, or Dictionary containing the top-level information regarding a contact in the XMDirectory.

Example Implementation¶

Here is an example on how to implement the list_contacts_in_directory() method. Let’s say that we want to pull in the information from 2 of our contacts in the middle of our XMDirectory. We know that we have 50 people in our XMDirectory. So we set our offset to 24, because this will start our slice at the 24th contact, and we also set our page_size to 2. Let’s say that we also want this to be returned as a Pandas DataFrame, so we pass True to the ‘to_df’ parameter (this is the Default Behavior).

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import XMDirectory

#Create an instance
x = XMDirectory()

#Call the method
df = x.list_XM_in_directory(page_size=2, offset=24, to_df=True)

This will return a pandas DataFrame containing the 2 contacts from your XMDirectory.

           contact_id   first_name last_name                       email phone unsubscribed  language external_ref
0  CID_FakeContactID1         John      Snow     'therealking@email.com'  None        False      'en'         None
1  CID_FakeContactID2         Bran     Stark          'b.stark@fake.net'  None        False      None         None

Get a Contacts information from the XMDirectory¶

XMDirectory.get_contact(contact_id=None)¶

This method is similar to the ‘list_contacts_in_directory’ method, in that it will return a single contact’s information.

Parameters: contact_id (str) – The unique id associated with each contact in the XM Directory.
Returns: A Pandas DataFrame containing the contact’s informaion

Example Implementation¶

Here is an example on how to call the get_contact() method.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import XMDirectory

#Create an instance
x = XMDirectory()

#Call the method
df = x.get_contact(contact_id='CID_FakeContactID')

#Print the DataFrames columns
df.columns

This will return a pandas DataFrame containing the contacts information contained in your XMDirectory. The type of information will populated the columns below.

Index(['contactId', 'creationDate', 'lastModified', 'firstName', 'lastName',
'email', 'emailDomain', 'phone', 'language', 'writeBlanks', 'extRef',
'embeddedData', 'transactionData', 'stats', 'skipped',
'directoryUnsubscribed', 'directoryUnsubscribeDate',
'mailingListMembership'])

Get the Additional Information about a Contact in the XMDirectory¶

XMDirectory.get_contact_additional_info(contact_id=None, content=None)¶

This method will return the additional “nested” information associated with a contact in the XMDirectory. To get these different nested pieces of infomation you can pass one of three arguements to the ‘content’ parameter. If you pass ‘mailinglistmembership’, you will return the different Mailing Lists that the contact is associated with in the form of a pandas DataFrame. If you pass ‘stats’, you will return the response statistics associated with the contact, again in the form of a Pandas DataFrame. Finally, if you pass the ‘embeddedData’ argument, you will return any emmbedded data associated with the given contact, and as you guessed it, in the form of a Pandas DataFrame.

Parameters

contact_id (str) – The unique id associated with each contact in the XM Directory.
content (str) – A string representing either ‘mailingListMembership’, ‘stats’, ‘embeddedData’

Returns

A Pandas DataFrame

Example Implementation¶

Here is an example on how to call the get_contact_additional_info() method.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import XMDirectory

#Create an instance
x = XMDirectory()

#Call the method
df = x.get_contact_additional_info(contact_id='CID_FakeContactID', content='mailingListMembership')

This will return a pandas DataFrame containing the MailingLists that the contact is on.

                 ML_FakeMailingListID
contactLookupId    MLRP_FakeContactID
name                       FakeMLName
unsubscribed                    False
unsubscribeDate                  None
ownerId                UR_FakeOwnerID